Summary

This PR improves the reliability of GSD's workflow transition layer — the handoffs between planning, execution, verification, and progress routing. Three issues addressed across 3 files, ~64 lines total.

Changes

1. Progress routing: include roadmap phases in init data — Closes #689

The experience: Running /gsd:progress announces "Milestone Complete! All phases finished!" even though 4+ phases remain in the roadmap — they just haven't been scaffolded to disk yet. This has reproduced consistently across multiple sessions for users with multi-phase milestones.

Why it happens: init progress builds its phase overview by scanning .planning/phases/ directories. Phases defined in ROADMAP.md that haven't been planned yet don't have directories, so phase_count and completed_count end up equal. The progress workflow sees completed_count === phase_count and routes to "Milestone Complete."

The issue author identified this clearly: the current_phase, next_phase, phase_count, and completed_count fields from init "look authoritative but only reflect disk state." The LLM treats this output as self-sufficient and skips the roadmap analyze step that would reveal the unscaffolded phases.

The fix: After the disk scan, parse ROADMAP.md for phase headings. Add a roadmap_phase_count field that reflects the true total from the roadmap. When all disk phases are complete but the roadmap defines more, set next_phase to the first unscaffolded phase (with a roadmap_only: true marker so consumers can distinguish it from disk phases). The existing phase_count field stays unchanged — it still means "directories on disk" — so existing consumers aren't affected.

Files: bin/lib/init.cjs (+33 lines)

2. Verify-work routing after execution — Closes #117

The experience: When gsd-verifier returns human_needed, the execute-phase workflow displays a static text block listing items that need manual testing. But the user must manually discover and invoke /gsd:verify-work to actually perform the tests. Users may miss the items entirely, proceed to the next phase without testing, or not realize the phase is unverified.

The fix: Replace the passive text display with an AskUserQuestion offering three clear paths:

• Start /gsd:verify-work — run the interactive UAT workflow (with /clear recommended for fresh context)
• Mark all approved — skip manual testing and proceed
• Review verification report — see the full VERIFICATION.md before deciding

This is complementary to PR #819 (browser pre-verification) — #819 makes the verification process itself smarter, while this fix makes the transition to verification automatic. They work well together.

Files: workflows/execute-phase.md (+16 lines, -8 lines)

3. Execute-phase offer after planning — Closes #136

The experience: After planning completes (in the non-auto-advance case), the workflow shows a static suggestion to run /gsd:execute-phase. The user has to read the suggestion, understand it, and manually invoke the command. This creates an unnecessary friction point in the plan-execute loop.

The fix: Add an AskUserQuestion to the <offer_next> section offering to execute immediately, review plans first, or clear context for a fresh start. This only fires when auto-advance is NOT enabled — the auto-advance path (step 14) already handles the transition automatically.

This is different from autopilot mode (#796): autopilot auto-advances through the full chain without asking. This fix is about the interactive case — offering a choice, not forcing execution. They're complementary features.

Files: workflows/plan-phase.md (+15 lines, -12 lines)

Verification

Overlap & Conflict Notes

This PR touches workflow files that are also modified by several active PRs from ethan-hurst:

• fix: convert inline questions to AskUserQuestion (#803) #807 (AskUserQuestion conversions) — our changes use AskUserQuestion, so they're semantically compatible
• feat: browser pre-verification for /gsd:verify-work #819 (browser pre-verification) — complementary to Auto-trigger /gsd:verify-work when gsd-verifier returns human_needed status #117 (different files, different concerns)
• feat: autopilot mode — full pipeline automation with synthetic multi-agent discuss #796 (autopilot mode) — complementary to Calling phase execution automatically after planning would be nice #136 (autopilot is auto, ours is interactive)

Our diff is small (~64 lines) and each commit is atomic, so rebasing after any of these merge should be straightforward. The maintainer can also cherry-pick individual commits if preferred.

Relationship to PR #822

PR #822 fixes the foundation-level bugs (phase lifecycle scanning, milestone detection, state parsing) that these workflow improvements depend on. Specifically:

• Bug: /gsd:progress routes to Milestone Complete when unscaffolded phases remain #689's fix is more effective when cmdPhaseComplete reports is_last_phase:true when future phases have no directories #709 (phase lifecycle) is also fixed — both address the "disk-only scanning" root cause, but at different layers (init vs phase-complete)
• Auto-trigger /gsd:verify-work when gsd-verifier returns human_needed status #117 and Calling phase execution automatically after planning would be nice #136 benefit from state-snapshot returns all nulls — regex format mismatch with STATE.md #730 (state parsing) being correct, since workflow routing depends on state data

These PRs can merge independently, but together they address the full chain from data layer through workflow routing.

v2 Changes (rebase on main after #826)

Rebased on current main per reviewer request. The rebase applied cleanly — no conflicts.

Regarding "commit recovery sections": After inspecting all three commits, neither discuss-phase.md nor plan-phase.md contain any commit recovery content. The branch has zero changes to discuss-phase.md. The plan-phase.md change only touches the <offer_next> section (replacing static "Next Up" text with AskUserQuestion routing), which is independent of #826's auto-advance <process> section. Both sections coexist cleanly.

🤖 Generated with Claude Code